PC-SIG: World of Games/PC-SIG World of Games (CDRM1080710) (1993).iso/ENT/DISK1232.ZIP/AGTNUM.ZOO/agtnum.doc

Text File | 1988-10-22 | 36KB | 1,218 lines

                                    AGTNUM

                   The Adventure Game Toolkit Number Manager




                                      By

                             William D. Martinson










                                Distributed by

                                   Softworks
                               43064 Via Moraga
                         Mission San Jose, California
                                     94539

                                [phone]





 The Adventure Game Toolkit Number Manager (AGTNUM), including all source code,
 object code, and manuals on paper or on disk, is copyright 1988 by William D.
 Martinson.  Portions of this document are borrowed from AGT-DOC.TXT, copyright
 1987 and 1988 by Mark J. Welch and David R. Malmberg.

 The Adventure Game Toolkit (AGT), including all source code, object code, and
 manuals on paper or on disk, is copyright 1987 and 1988 by Mark J. Welch and
 David R. Malmberg.  Portions originally copyright 1985 and 1986 by Mark J.
 Welch.



 COPYRIGHT, TRADEMARKS, WARRANTY, AND LICENSE

      AGTNUM is provided to users of the Adventure Game Toolkit (AGT), and as
 such is subject to the copyright, warranty, and license conditions of AGT.
 Specifically, all such conditions that apply to COMPILE.EXE shall be construed
 as applying to AGTNUM.EXE as well.

      "Adventure Game Toolkit" and "AGT" are trademarks of Mark J. Welch and
 David R. Malmberg.


 DISCLAIMER

      THE ADVENTURE GAME TOOLKIT NUMBER MANAGER (AGTNUM) COMES WITH NO OTHER
 WARRANTIES OF ANY KIND, INCLUDING WARRANTY OF MERCHANTABILITY OR OF FITNESS
 FOR A PARTICULAR PURPOSE.  AGTNUM IS AVAILABLE AS IS.  IN NO EVENT WILL THE
 AUTHOR OR DISTRIBUTOR BE LIABLE FOR DAMAGES, INCLUDING ANY LOST PROFITS OR
 INCIDENTAL AND CONSEQUENTIAL DAMAGES, EVEN IF THE AUTHOR AND/OR DISTRIBUTOR
 HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.


 REGISTRATION

      AGTNUM registration is included with all past, present, and future AGT
 registrations, at no additional cost.


 PRODUCT/TECHNICAL SUPPORT

      The author will make every reasonable effort to fix AGTNUM bugs, and help
 registered users by answering technical and other AGTNUM-related questions.
 This product/technical support for AGTNUM is available to registered AGT users
 (only) in several forms, listed in order of preference:

      (1)  By letter to:  William D. Martinson
                          Post Office Box 1606
                          Beaverton, Oregon  97075-1606

      (2)  By telephone to Bill Martinson, Monday through Friday from 7:00 PM
           to 9:00 PM (Pacific Coast Time) at [phone], subject to my
           availability.  Please respect these hours.

      (3)  By leaving a message in the 'Softworks' forum on BIX (the BYTE
           Information Exchange).

      (4)  By CompuServe E-Mail to David Malmberg, CompuServe ID 73435,1277.

 If you send disks or listings that you wish returned, be sure to enclosed a
 self-addressed, stamped envelope (SASE) with sufficient postage.  If you do
 not enclose a SASE, your material will not be returned.

 BIX and CompuServe correspondence will be routed to Bill Martinson through
 Softworks, so option (1) above will likely result in the fastest turnaround.

 Softworks does not provide telephone support for AGTNUM.  That's my
 responsibility, so please don't call David or Mark with AGTNUM questions.


                                       i


                               TABLE OF CONTENTS


 COPYRIGHT, TRADEMARKS, WARRANTY, AND LICENSE  . . . . . . . . . . . . . . .  i

 REGISTRATION  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  i

 PRODUCT/TECHNICAL SUPPORT . . . . . . . . . . . . . . . . . . . . . . . . .  i

 PART 1: INTRODUCTION  . . . . . . . . . . . . . . . . . . . . . . . . . . .  1

 PART 2: HOW TO USE AGTNUM . . . . . . . . . . . . . . . . . . . . . . . . .  2
      THE .ALL FILE  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  2
      LABELS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  2
      LABEL DEFINITIONS  . . . . . . . . . . . . . . . . . . . . . . . . . .  2
      PRINTING SHORT MESSAGES FROM META-COMMANDS . . . . . . . . . . . . . .  3
      TEXT MACROS  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
      MACRO NESTING AND RECURSION  . . . . . . . . . . . . . . . . . . . . .  6
      MULTI-LINE MACROS  . . . . . . . . . . . . . . . . . . . . . . . . . .  7
      TITLE AND INSTRUCTIONS TEXT  . . . . . . . . . . . . . . . . . . . . .  7

 PART 3: CUSTOMIZING AGTNUM  . . . . . . . . . . . . . . . . . . . . . . . .  8
      CASE SENSITIVITY . . . . . . . . . . . . . . . . . . . . . . . . . . .  8
      DELIMITERS AND KEYWORD CHARACTER . . . . . . . . . . . . . . . . . . .  8
      MACRO NESTING  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9
      ASSUMED FILENAME EXTENSION . . . . . . . . . . . . . . . . . . . . . .  9
      MAKING OPTIONS PERMANENT . . . . . . . . . . . . . . . . . . . . . . .  9

 APPENDIX A: EXAMPLES  . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

 APPENDIX B: KEYWORDS THAT DEFINE LABELS . . . . . . . . . . . . . . . . . . 14
      AGT KEYWORDS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
      AGTNUM KEYWORDS  . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

 APPENDIX C: AGTNUM COMMAND-LINE OPTIONS . . . . . . . . . . . . . . . . . . 15

 APPENDIX D: AGTNUM ERROR MESSAGES . . . . . . . . . . . . . . . . . . . . . 16
      WARNINGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
      ERRORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
      FATAL ERRORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17


















                                      ii


 PART 1: INTRODUCTION


 AGTNUM is a sort of "preprocessor" for the AGT compiler.  It is intended to
 simplify the creation and maintenance of the .DAT, .CMD, and .MSG files used
 by the COMPILE program.  AGTNUM provides the following benefits to the game
 designer:

      (1)  A single source file is used, which ecompasses everything from the
           .DAT, .CMD, .MSG, .TTL, and .INS files.  Corresponding commands and
           messages can be placed together in the file, and they can immedi-
           ately follow the room, noun, or creature they affect.  AGTNUM
           handles the task of creating the necessary files and writing the
           appropriate information to each.

      (2)  Items such as rooms, creatures, messages, and variables can be
           automatically numbered, and then referred to with user-defined
           labels.

      (3)  Short messages can be printed from within meta-commands without
           explicitly providing a MESSAGE definition.

      (4)  Simple text macros make it easy to modify items that appear in many
           locations throughout the file.

      (5)  The use of these features makes the game file self-documenting to a
           great extent.

 To use the program, just enter

      AGTNUM filename

 at the DOS prompt.  If the filename has no extension, an extension of ".ALL"
 will be assumed.  (To use a file with no extension, be sure to append a period
 to the filename.)  If no filename is specified, a brief help screen will be
 displayed.






















                                       1


 PART 2: HOW TO USE AGTNUM


 THE .ALL FILE

 AGTNUM reads a single file, usually with an extension of .ALL.  This file
 should contain everything that would normally go into the .DAT, .CMD, and .MSG
 files.  AGTNUM then parses the file, creates the .DAT, .CMD, and .MSG files,
 and writes the appropriate game elements to each of those files.

 Optionally, the title and instructions text can also be included in the .ALL
 file and AGTNUM will create the .TTL and .INS files.


 LABELS

 The .ALL file looks very much like the files it creates.  The main difference
 is that it uses text labels instead of numbers for rooms, nouns, and the like.
 The labels are enclosed in delimiters, which are braces { } by default.  (This
 can be changed; refer to Part 3.)  Labels may consist of any ASCII characters
 (even whitespace characters), except the closing delimiter.  For example, the
 following labels are all legal (and unique):

      {bridge}
      {the captain's quarters}
      {transporter pad number 6}
      { transporter pad number 6 }
      {!@#$%^&*()}
      {{{{{{}
      {!}
      { }
      {  }

 The null label {} is not allowed.  AGTNUM is insensitive to case by default,
 so {bridge} and {BRIDGE} are considered identical.  (This can be changed;
 refer to Part 3.)

 When AGTNUM parses the .ALL file, it assigns appropriate numbers to the
 labels.  When the output files are written, the numbers are substituted for
 the labels.  (The .ALL file is not changed by AGTNUM.)


 LABEL DEFINITIONS

 When AGTNUM encounters a label, it must determine what type of item the label
 refers to (room, message, flag, etc.).  For some items, the normal item
 definition gives this information.  Consider this example:

      ROOM {sickbay}                            (* {sickbay} is a ROOM label *)
      Sickbay
      EXIT {corridor}
      END_ROOM
      ROOM_DESCR {sickbay}
      This is the sickbay, where the regulars are cured of all their ails and
      the extras meet slow, painful deaths.
      END_ROOM_DESCR


                                       2

 In this case, the word "ROOM" at the beginning of the line tells AGTNUM that
 {sickbay} is a label for a room.  Labels for nouns, creatures, messages, and
 questions are determined in the same way.

 Other AGT items, such as flags and variables, have no such definition.  Since
 a label for one of these items may appear practically anywhere in the file,
 AGTNUM requires you to declare the type of item it refers to, to ensure proper
 numbering.  For this purpose, AGTNUM introduces some special keywords:

      FLAG {label}
      COUNTER {label}
      VARIABLE {label}

 Each of these keywords appears on its own line, anywhere in the file.  They do
 not have any effect on the structure of the game, but simply tell AGTNUM what
 type of item the label refers to.  For example:

      FLAG {flashlight lit}
      VARIABLE {energy left}
      ...
      COMMAND ANY
           Present {flashlight}
           FlagON {flashlight lit}
           VariableLT {energy left} 20
      END_COMMAND
      MESSAGE {batteries dying}
      Your batteries will last only #VAR{energy left}# more turns.
      END_MESSAGE

 These keywords cause the labels to be defined with the next available number
 for the particular item.  For example, if there were already four other
 variables defined, AGTNUM would assign the value 5 to the label {energy left}
 upon encountering the VARIABLE definition.


 PRINTING SHORT MESSAGES FROM META-COMMANDS

 AGTNUM provides a short-cut for printing simple messages from within meta-
 commands:  simply put the message in quotation marks following the
 PrintMessage token; no label is necessary.  Consider this example:

      COMMAND FIRE PHASER
           IsCarrying {phaser}
           VariableEquals {phaser shots} 0
           PrintMessage {phaser empty}
      END_COMMAND
      MESSAGE {phaser empty}
      The phaser is out of energy.
      END_MESSAGE

 The message short-cut allows the game designer to abbreviate this command as
 follows:

      COMMAND FIRE PHASER
           IsCarrying {phaser}
           VariableEquals {phaser shots} 0
           PrintMessage "The phaser is out of energy."
      END_COMMAND

                                       3


 AGTNUM will translate the quoted text following the PrintMessage token into a
 message number, and create a corresponding message definition in the .MSG
 file.

 AGTNUM searches for the quotation marks "from the outside in," so messages
 that require quote marks as part of the text are possible:

      PrintMessage "This message has "quotation marks" in it."
      PrintMessage ""Aye, aye, sir.""

 The first and last quotes are removed from the message; all others are left
 intact.  (If you find these "nested" quotes confusing or undesirable, you can
 change the short-cut message delimiter characters; refer to Part 3.)

 If no closing quote is found, the message is assumed to extend to the end of
 the line.  Thus, the following message is perfectly legal:

      PrintMessage "You can't eat the rock.

 Of course, if the message itself contains quote marks, then a closing message
 delimiter must be supplied to mark the end of the message--otherwise the last
 quote mark would signal the end of the text.  For example:

      PrintMessage "This message has "embedded" quotes.

 Without a closing quote, this message would be printed as follows:

      This message has "embedded

 and AGTNUM would assume the remaining text on the line was a comment.

 Naturally, the short-cut message style is not appropriate for multi-line
 messages, or messages which can be printed from more than one meta-command.
 For short, specialized messages, however, this style can eliminate a lot of
 typing and reduce the size of the .ALL file.


 TEXT MACROS

 A text macro is simply a special kind of label that can be defined as any text
 string the game designer chooses.  AGTNUM provides a special keyword for
 defining macros:

      #DEFINE {label} label definition

 This keyword causes the label to be defined as all text after the label to the
 end of the line (not including the first character after the label, which is
 normally a blank).  This keyword is useful for defining macros for "constants"
 used throughout the game file:

      rem macros for special "rooms"
      #DEFINE {void} 0
      #DEFINE {carried} 1
      #DEFINE {worn} 1000




                                       4

      rem macros for the directions used with ChangePassageway
      #DEFINE {North} 1
      #DEFINE {South} 2
      #DEFINE {East} 3
      #DEFINE {West} 4
      #DEFINE {NorthEast} 5
      #DEFINE {NorthWest} 6
      #DEFINE {SouthEast} 7
      #DEFINE {SouthWest} 8
      #DEFINE {Up} 9
      #DEFINE {Down} 10
      #DEFINE {Enter} 11
      #DEFINE {Exit} 12

 It's sometimes handy to use a macro for something you may want to change, so
 you don't have to track down all the occurrences of the item.  For example:

      VARIABLE {health}
      #DEFINE {max health} 100
      #DEFINE {rest delay} 5
      #DEFINE {rest benefit} 20
      ...
      COMMAND REST
           TimePasses
           Delay {rest delay}
           PrintMessage "Having rested for a while, you now feel much better."
           AddToVariable {health} {rest benefit}
           VariableGT {health} {max health}
           SetVariableTo {health} {max health}
           DoneWithTurn
      END_COMMAND

 This allows the game designer to quickly change, say, the maximum health the
 player can have, no matter how many times that value is referred to in the
 file.  Here's another example, adapted from the Colossal Cave Adventure:

      #DEFINE {magic word} XYZZY
      ...
      Dummy_Verb17 {magic word}
      ...
      ROOM_DESCR {debris room}
      You are in a debris room filled with stuff washed in from the surface.  A
      low wide passage with cobbles becomes plugged with mud and debris here,
      but an awkward canyon leads upward and west.  A note on the wall says:
           Magic Word "{magic word}"
      END_ROOM_DESCR
      ...
      COMMAND {magic word}
           FlagOFF {cave closed}
           AtLocation {debris room}
           PrintMessage {transported}
           GoToRoom {inside building}
           DoneWithTurn
      END_COMMAND
      ...




                                       5

      COMMAND {magic word}
           FlagOFF {cave closed}
           AtLocation {inside building}
           PrintMessage {transported}
           GoToRoom {debris room}
           DoneWithTurn
      END_COMMAND
      ...
      COMMAND {magic word}
           PrintMessage "A voice booms out, "That word doesn't work here!""
           DoneWithTurn
      END_COMMAND

 AGTNUM allows up to 500 macros in a game file.


 MACRO NESTING AND RECURSION

 By default, macros are "nestable", meaning that they can include references to
 other labels.  When a macro is expanded, the resulting text is then scanned
 for additional macros and labels.  (This can be changed; refer to Part 3.)
 The following example makes use of macro nesting:

      NOUN {burning torch}
      ...
      NOUN {unlit torch}
      ...
      #DEFINE {extinguish} SwapLocations {burning torch} {unlit torch}
      ...
      COMMAND ANY
           FlagON {wind blowing}
           Chance 10
           PrintMessage "The wind blows out your torch."
           {extinguish}
      END_COMMAND

 The danger with nestable labels is this:  if a macro refers to itself, either
 directly or indirectly, then the macro's final value cannot be determined.
 AGTNUM would spend eternity trying to expand the macro, forever ending up with
 another macro.  For example:

      #DEFINE {yoyo} xx {yoyo} xx

 AGTNUM will define a macro called {yoyo} with the text "xx {yoyo} xx".  When
 the macro is expanded, a new macro (also called {yoyo}) is discovered which
 must itself expanded, ad infinitum.  Here's another example, using indirect
 recursion:

      #DEFINE {tweedle dee} {tweedle dum}
      #DEFINE {tweedle dum} {tweedle dee}

 To handle recursive macros, AGTNUM will display an error message if more than
 30 macro expansions are performed on a single line of the file.






                                       6

 MULTI-LINE MACROS

 To write a macro that expands to multiple lines of text, use the two
 characters '\n' to represent the newline, or carriage return.  For example, if
 a number of meta-commands depend on the presence of the sword, axe, or mace,
 the following macro could be useful:

      #DEFINE {armed} Present {sword}\nOR\nPresent {axe}\nOR\nPresent {mace}

 This macro could be used in the meta-commands as follows:

      COMMAND BREAK LOCK
           {armed}
           InRoom {oak door}
           ...
      END_COMMAND


 TITLE AND INSTRUCTIONS TEXT

 To identify the text for the game title and instructions, AGTNUM provides some
 additional keywords:

      TITLE
      The game title goes here, in the .TTL file format.
      END_TITLE

      INSTRUCTIONS
      The game instructions go here, in the .INS file format.
      END_INSTRUCTIONS

 When one of these keywords is found, AGTNUM creates the appropriate file and
 writes the description (without the keywords) to the file.  If one or both of
 these are omitted, AGTNUM will ignore the .TTL and/or .INS file, to allow the
 game designer to maintain these files manually if desired.

 Macros and labels may be used in the title and instructions text.






















                                       7


 PART 3: CUSTOMIZING AGTNUM


 You can customize AGTNUM's operation through the use of several command-line
 options (letters preceded by a slash [/] or dash [-]).  The options should
 follow the filename on the command line, and may appear in any order.  If
 conflicting options are given, the last one given will override the earlier
 ones.


 CASE SENSITIVITY

 AGTNUM is case insensitive by default, which means that uppercase and lower-
 case letters are treated as identical.  For example, the labels {sickbay} and
 {SICKBAY} are considered to be the same label.  To make AGTNUM case sensitive,
 specify /C on the command line.  /I will override this and make AGTNUM case
 insensitive.

 When AGTNUM is case sensitive, keywords such as ROOM and VARIABLE *must* be
 typed in all capital letters in the .ALL file, or they will not be recognized.


 DELIMITERS AND KEYWORD CHARACTER

 The default delimiters for labels are the braces ({ and }), the delimiters for
 short-cut messages are the quote marks ("), and the lead-in character for the
 AGTNUM keyword DEFINE is the number sign (#).

 To change the label delimiters, specify /Loc (where 'o' and 'c' are the new
 opening and closing delimiter characters).  If you leave off the second
 character, the first one will be used for both; for example:

      AGTNUM MYGAME /L!

 tells AGTNUM that the labels in MYGAME.ALL are of the form !label!.

 To change the message delimiters, specify /Moc (where 'o' and 'c' are the new
 opening and closing delimiter characters).  For example:

      AGTNUM MYGAME /M`'

 tells AGTNUM that the short-cut messages in MYGAME.ALL are of the form
 PrintMessage `message'.  As with the /L option, leaving off the second
 character causes the first one to be used for both delimiters.

 To change the lead-in character for the #DEFINE keyword, specify /Kc, where
 'c' is the new lead-in character.  For example:

      AGTNUM MYGAME /K%

 tells AGTNUM that macro definitions in MYGAME.ALL begin with %DEFINE.

 If you give one of these options without any characters after it, the current
 character(s) will be displayed.  For example:

      AGTNUM MYGAME /K /L /M


                                       8

 will yield the response:

      Keyword character is #
      Label delimiters are { and }
      Messg delimiters are " and "

 To use the DOS meta-characters <, >, and | with these options, enclose the
 entire option string in quotes.  For example:

      AGTNUM MYGAME "/L<>" "/M|"


 MACRO NESTING

 Macros, by default, are "nestable", meaning that they can refer to other
 labels.  To make them static, or not nestable, specify /S.  To make then
 nestable again, specify /N.  Static macros are not re-scanned for new labels
 after they are expanded.  Making macros static allows error-free processing of
 macros such as

      #DEFINE {left brace} {
      #DEFINE {legal null} {}

 but prevents the following definition from working properly:

      #DEFINE {extinguish} SwapLocations {burning torch} {unlit torch}


 ASSUMED FILENAME EXTENSION

 The default assumed filename extension is .ALL.  This extension is appended to
 any filename that lacks an extension.  To change the extension, specify /Xext,
 where 'ext' is the new extension (do not include the period).  For example:

      AGTNUM MYGAME /XAGT

 Of course, this example is a kind of silly.  It would be easier to type

      AGTNUM MYGAME.AGT

 since AGTNUM allows an extension as part of the filename.  The primary use of
 /X is in the environment variable, to change the assumed extension on a more-
 or-less permanent basis (see below).


 MAKING OPTIONS PERMANENT

 Since it would be inconvenient to have to specify these options each time you
 use AGTNUM, a DOS environment variable is supported.  Put a line of the form

      SET AGTNUM= options

 in your AUTOEXEC.BAT file and reboot your computer, and AGTNUM will auto-
 matically use the new options.  Options given on the command line override the
 options in the environment variable.  For example, if your AUTOEXEC.BAT file
 contains the line

      SET AGTNUM="/L<>"

                                       9


 AGTNUM will expect labels to be enclosed in angle brackets from now on.
 However, if you type

      AGTNUM MYGAME /L{}

 AGTNUM will temporarily expect labels to be enclosed in braces in MYGAME.ALL.

 If you later decide to edit your AUTOEXEC.BAT file to change the options
 again, be sure to reboot your computer to put the new options in place.

 You can also use this variable to specify a default filename.  If you tend to
 work on a single game file at a time, you can include the filename in the
 option string and have AGTNUM process that file if no other file is specified
 on the command line.  For example, if your AUTOEXEC.BAT file has the line

      SET AGTNUM= MYGAME /L[]

 then you can process MYGAME.ALL, looking for labels in square brackets, by
 simply entering the command

      AGTNUM

 Naturally, you can override this default filename by specifying one on the
 command line.

 See your DOS manual for more details on environment variables and the SET
 command.































                                      10


 APPENDIX A: EXAMPLES


 Here is a short excerpt from a sample .ALL file:

      ROOM {bridge}
      Bridge
      SOUTH {turbolift}
      END_ROOM
      ROOM_DESCR {bridge}
      You are on the bridge of the Enterprise.
      END_ROOM_DESCR

      NOUN {phaser}
      Phaser
      Hand
      There is a hand phaser here.
      LOCATION {bridge}
      CAN_SHOOT
      NUM_SHOTS 999
      SIZE 2
      END_NOUN
      NOUN_DESCR {phaser}
      This is a standard box-shaped Phaser I.  While not as powerful as the
      pistol-shaped Phaser II, it is considerably more compact and thus easily
      concealed.
      END_NOUN_DESCR

      COMMAND FIRE PHASER
           AtLocation {bridge}
           IsCarrying {phaser}
           PrintMessage {destroy bridge}
           EndGame
      END_COMMAND
      MESSAGE {destroy bridge}
      You fire the phaser.  The bridge wall is ruptured, and the area rapidly
      depressurizes.  You are killed, along with the rest of the bridge crew.
      END_MESSAGE

      ROOM {turbolift}
      Turbolift
      NORTH {bridge}
      END_ROOM
      ROOM_DESCR {turbolift}
      You are in the turbolift.
      END_ROOM_DESCR


 When AGTNUM parses this file, it will assign numbers to the labels as follows:

      {bridge}           2
      {turbolift}        3
      {phaser}         200
      {destroy bridge}   1




                                      11

 Here's the flashlight example from AGT-DOC.TXT, modified to exploit some
 AGTNUM features.  Notice that the file is still very readable, even though
 many of the original comments have been deleted.

      FLAG {game started}     is OFF at start of game and ON otherwise
      FLAG {flashlight lit}   is OFF if the flashlight is OFF & ON if it is ON
      VARIABLE {batt life} will count down the life of the battery

      #DEFINE {initial battery charge} 100
      #DEFINE {battery warning level} 20

      ; Noun {off flashlight} is FlashLight in OFF condition
      ; Noun {on flashlight} is FlashLight in ON condition
      ; Noun {dead flashlight} is FlashLight in DEAD condition

      COMMAND ANY
        FlagOFF {game started} (* First game turn -- initialize Battery life *)
        SetVariableTo {batt life} {initial battery charge}
        TurnFlagON {game started} (* Initialization process is now over *)
      END_COMMAND

      COMMAND ANY
        FlagON {flashlight lit}
        SubtractFromVariable {batt life} 1
      END_COMMAND

      COMMAND ANY
        FlagON {flashlight lit}
        Present {on flashlight} (* No warning unless Flashlight here *)
        VariableGT {batt life} 0
        NOT VariableGT {batt life} {battery warning level}
        PrintMessage "Flashlight will last only #VAR{batt life}# more turns!"
        VariableEquals {batt life} {battery warning level}
        PrintMessage "You had better save your batteries!"
      END_COMMAND

      COMMAND ANY
        FlagON {flashlight lit}
        VariableEquals {batt life} 0
        TurnFlagOFF {flashlight lit} (* Turn it off for the last time! *)
        SwapLocations {on flashlight} {dead flashlight}
        Present {dead flashlight} (* No message unless Flashlight here *)
        PrintMessage "The Flashlight's batteries are dead!!"
      END_COMMAND

      COMMAND LIGHT FLASHLIGHT
        Present {off flashlight}
        TurnFlagON {flashlight lit}
        SwapLocations {off flashlight} {on flashlight}
        PrintMessage "The flashlight is ON and shining brightly!"
        DoneWithTurn
      END_COMMAND

      COMMAND LIGHT FLASHLIGHT
        Present {on flashlight}
        PrintMessage "The flashlight is already ON, dummy!"
        DoneWithTurn
      END_COMMAND

                                      12


      COMMAND LIGHT FLASHLIGHT
        Present {dead flashlight}
        PrintMessage "Sorry, but the batteries are dead!"
        DoneWithTurn
      END_COMMAND

      COMMAND EXTINGUISH FLASHLIGHT
        Present {on flashlight}
        TurnFlagOFF {flashlight lit}
        SwapLocations {off flashlight} {on flashlight}
        PrintMessage "The flashlight is now off!"
        DoneWithTurn
      END_COMMAND

      COMMAND EXTINGUISH FLASHLIGHT
        Present {off flashlight}
          OR
        Present {dead flashlight}
        PrintMessage "The flashlight is already OFF!"
        DoneWithTurn
      END_COMMAND





































                                      13


 APPENDIX B: KEYWORDS THAT DEFINE LABELS


 The value of each label is the next number in sequence for the kind of item
 the label refers to.  For macros (#DEFINEd labels), the label's value is
 whatever the game designer chooses.


 AGT KEYWORDS

      ROOM      {label}
      NOUN      {label}
      CREATURE  {label}
      MESSAGE   {label}
      QUESTION  {label}


 AGTNUM KEYWORDS

      FLAG      {label}
      COUNTER   {label}
      VARIABLE  {label}
      #DEFINE   {label} label definition (AGTNUM allows 500 #DEFINEs)



































                                      14


 APPENDIX C: AGTNUM COMMAND-LINE OPTIONS


      /C        Make AGTNUM case sensitive.

      /I        Make AGTNUM case insensitive.

      /Kc       Make 'c' the new keyword lead-in character.

      /Loc      Make 'o' and 'c' the new opening and closing label delimiters.
                If 'c' is omitted, 'o' will be used for both delimiters.

      /Moc      Make 'o' and 'c' the new opening and closing short-cut message
                delimiters.  If 'c' is omitted, 'o' will be used for both
                delimiters.

      /N        Make macros nestable.

      /S        Make macros static (not nestable).

      /Xext     Make 'ext' the new assumed filename extension.

      /?        Display a help screen.

 Options may be preceded by a dash (-) instead of a slash (/).

































                                      15


 APPENDIX D: AGTNUM ERROR MESSAGES


 Errors reported by AGTNUM fall into three categories:  warnings, errors, and
 fatal errors.

 Warnings are conditions which should be noted by the game designer.  They may
 be indicative of errors, but the file can be processed normally in spite of
 them.  It is entirely possible for a game file to have warnings and still
 operate as the game designer intended.

 Errors generally result from mistyped or incorrect labels, and probably
 indicate problems that will cause the game to operate incorrectly.  AGTNUM
 continues to process the file in spite of the errors, for two reasons:

      (1)  There may be additional warnings and errors in the file, and it's
           useful to display as many of them as possible to allow the game
           designer to correct more than one problem at a time.

      (2)  The "error" may in fact be legitimate.  For example, the game
           designer may wish to have one or more braces as part of some game
           text.  AGTNUM would report an undefined or null label, or a missing
           closing delimiter, when no error actually existed.

 Fatal errors are serious conditions that prevent AGTNUM from continuing,
 either because of an internal problem or because it's very likely the output
 files will not make it through the COMPILE program.


 WARNINGS

 Label(s) defined but not referenced

      One or more labels were defined but not used elsewhere in the file.
      These are sometimes the result of typographical errors, and often will
      "match up" with other error messages.  For example, if a label is
      referred to only once and either the definition or the reference is
      mistyped, the definition will be reported under this warning and the
      reference will generate an "Undefined label" error.


 ERRORS

 No closing delim

      An opening label delimiter was found without a subsequent closing
      delimiter.  Probably a typo.

 Null label

      The null label {} was encountered.  If you actually need these two
      characters in a message, and if macro nesting is disabled, try using a
      macro (e.g., #DEFINE {braces} {}) to eliminate this "error" message.





                                      16

 Label not defined

      A label is being referred to but has not been defined anywhere in the
      file.  If the label represents a flag, counter, or variable, you need a
      FLAG, COUNTER, or VARIABLE line in the file.  This is also often the
      result of a typo.

 Label redefined

      A label definition has been found, and the label is already defined.
      This could be a typo, or you could have (for example) both a ROOM and a
      NOUN called {fountain}.  Change one of the label names.

 No #define text

      A line beginning with the keyword #DEFINE contains a label but no text to
      define the label with.

 Macro recursion

      The limit of 30 macro expansions per line was exceeded, probably because
      a macro refers to itself (either directly or indirectly).

 Macro too long

      Expansion of a macro would cause the line to be too long for AGTNUM to
      handle.  This error can also be caused by macro recursion, if the maximum
      line length is exceeded before 30 expansions have been performed.


 FATAL ERRORS

 Line too long

      A line in the .ALL file is longer than 254 characters.  If the line
      contains a multi-line short-cut message, either shorten the message or
      don't use the short-cut format.

 Too many rooms (nouns/creatures/messages/questions/flags/counters/variables)

      Your game file has more of the item in question than AGT allows.  You
      will probably need to restructure the game.

 Too many #defines

      Your game file has more #DEFINEd labels than AGTNUM allows.  You will
      probably need to convert some of your label references into regular text.

 Out of memory

      AGTNUM has run out of memory while trying to define or expand a label.
      If you are running AGTNUM in a multi-tasking environment, or with a lot
      of resident utilities, you may need to remove some processes or utilities
      to free additional memory.





                                      17